home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_300 / 323_01 / explod.doc < prev    next >
Encoding:
Text File  |  1990-08-04  |  9.1 KB  |  229 lines
  1.                             EXPLOD 2.03
  2. PURPOSE
  3.         EXPLOD is a fireworks program for the Hercules, VGA, EGA, or CGA 
  4.     graphics cards.  
  5.  
  6. FILES
  7.     run.bat        - run this if you don't want to read the rest of this
  8.     explod.doc    - this file
  9.     explod.exe    - program to display fireworks 
  10.     *.dat        - explosion data files
  11.     expgen.exe    - program to generate explosion data files
  12.     explod.c    - fireworks display main source code
  13.     expa.asm    - fireworks display support routines 
  14.     maketc.bat    - compile script for use with Turbo C and MASM
  15.     expgen.c    - data file generator source code
  16.     example.c    - example of how to generate data files
  17.     star.tra    - star transformation data file
  18.     expgdemo.bat    - demo that shows how to use expgen.exe
  19.  
  20. HOW TO RUN
  21.     The command format is:
  22.  
  23.         explod [optional parameters] <data files>
  24.  
  25.     Optional parameters can be one of:
  26.  
  27.      -vC :C = Video type.  CGA:'-vc'  HGC:'-vh'  EGA:'-ve'  VGA:'-vv'
  28.           Default is auto-detect.  VGA users should use -ve for the
  29.           best results with the supplied data files.
  30.  
  31.      -sN :N = # of simultaneous explosions on the screen at a time. 
  32.           Default: 10 (8 for CGA).  This parameter controls how often
  33.           explosions are created.
  34.  
  35.      -dN :N = Delay factor.  Default: 0   
  36.           The delay to use depends on the machine speed and the number 
  37.           of simultaneous explosions (see -s).  Typical values when 10
  38.           simultaneous explosions are used are 0 for a 8Mhz XT and 6 for 
  39.           a 12 Mhz AT.
  40.  
  41.      -nN :N = Number of explosions to display before exiting.  Default=0.
  42.           0 means infinite.  Use a small value for this parameter in order 
  43.           to turn this program into a fancy screen clearer.
  44.  
  45.      -gN :N = Gravity.       Default: CGA=15 HGC=20 EGA=20
  46.           This parameter is used to override the gravity values specified 
  47.           in the data files.  Gravity is the vertical acceleration acting
  48.           on the particles in an explosion.  Negative gravity values 
  49.           (eg. "-g-50") are allowed; they cause acceleration upwards.
  50.  
  51.      -wN :N = Wind.          Default: 0   Typical Values: -50 to 50
  52.           Wind is the horizontal acceleration acting on the particles in 
  53.           an explosion.  Positive values blow to the right and negative
  54.           values blow to the left.
  55.  
  56.      -f  :Fill screen with explosion trails.  This creates a screen 
  57.           full of multicoloured dots for those who like such things.
  58.  
  59.     Keyboard Control:
  60.  
  61.       Pressing ESCAPE will exit the program.  Pressing any other key will
  62.       cause an additional explosion to be started.  The position of the
  63.       explosion roughly corresponds to the position of the key on the
  64.       keyboard; the space bar will start an explosion at a random place.
  65.       NOTE: if you use DOS 3.2 and you pound on the keys too fast then
  66.             you may get a DOS stack overflow error which will lock up 
  67.         your machine.
  68.  
  69.     Examples:
  70.        explod round.dat              (single explosion type, 8MHz XT)
  71.        explod -s5 -t3 round.dat diag.dat        (4.77MHz XT with CGA)
  72.        explod -t10 -s15 *.dat            (for 8MHz 80186 XT with HGC)
  73.        explod -s10 -w1000 *.dat               (for 8 Mhz AT with EGA)
  74.        explod -ve -w20 -d6 *.dat             (for 12 Mhz AT with VGA)
  75.        explod -s0 *.dat       (full manual control of all explosions)
  76.        explod -s50 -n5 -d10 round.dat       (use as a screen clearer)
  77.  
  78.     A summary of these instructions is displayed briefly if the program 
  79.     is run without any parameters.
  80.  
  81. DATA FILE FORMAT
  82.     Each data file describes the structure of one type of explosion.
  83.     They are pure ascii files that can be manually created with an text
  84.     editor, generated by the program expgen.exe, or generated by simple 
  85.     programs that you write in the language of your choice.  
  86.  
  87.     An explosions consists of a set of points moving from their source
  88.     positions to their destination positions.  The data file gives the
  89.     number of points, the number of frames (steps) to animate the 
  90.     explosion in, the vertical and horizontal accelerations (gravity
  91.     and wind), and the trail length (each point leaves a trail as it
  92.     moves).  
  93.  
  94.     In addition to the specified accerlerations, each point has an 
  95.     initial velocity towards its destination and a constant deceleration 
  96.     away from the destination.  These are calculated such that the point 
  97.     will have zero velocity when it reaches its destination in the
  98.     given number of frames (time units).  (The equations used are 
  99.     distance = 0.5 * accel * time^2, and velocity_change = accel * time.)
  100.  
  101.     The following is an example of a data file:
  102.  
  103.         # EXPLOD DATA FILE
  104.         300  # Number of points (max is 420)
  105.          50  # Number of frames  (max is 80)
  106.           9  # Gravity 
  107.           0  # Wind
  108.           5  # Trail length 
  109.         0 0  -39 4
  110.         0 0  40 -33
  111.         0 0  -45 -16
  112.          ...296 more lines like these
  113.         0 0  -68 47
  114.  
  115.     The first line of the data file must start with the string
  116.     "# EXPLOD DATA FILE".  The next 5 lines give the explosion 
  117.     parameters.  Each following line contains a source (x,y) and 
  118.     destination (x,y) locations of one point.  There should be the 
  119.     same number of these src-dest lines as the number specified in the
  120.     second line of the file.  Each x-y value represents a location
  121.     in Cartesian coordinates with the centre of the explosion being
  122.     (0,0).  Values are in units of screen pixels.  
  123.  
  124.     For example, consider the following four explosion points:
  125.  
  126.         0 0  12 3
  127.         0 0  8 -2
  128.         0 0  -5 2
  129.             0 0  -7 -3
  130.  
  131.     Their relative screen positions would be as follows (the centre of
  132.     the explosion is (0,0)):
  133.  
  134.                         |
  135.                         |          (12,3)
  136.               (-5,2)    |          .
  137.                    .    |
  138.                 |(0,0)
  139.               --------------+--------------
  140.                         |
  141.               (-7,-3)   |      . (8,-2)
  142.                  .      |
  143.                         |
  144.  
  145.     Comments can follow the numbers on any of the lines. (The example 
  146.     uses a '#' delimiter, but none is actually required).
  147.  
  148.     For example, to generate an 'explosion' that consists of the four
  149.     points at the corners of a square imploding into their centre, the 
  150.     following data file can be used:
  151.     
  152.         # EXPLOD DATA FILE
  153.         4    Number of points in the explosion
  154.         60   Number of frames 
  155.         9    Gravity 
  156.         0    Wind
  157.         10   Trail length 
  158.         -100 100  0 0
  159.         100 100  0 0
  160.         100 -100 0 0
  161.         -100 -100  0 0
  162.  
  163.     It is often easier to generate data files for geometric-shaped
  164.     explosions by writing a program instead of entering each point
  165.     by hand.  See the file expgen.c for an example of such a program.
  166.     You should be able to use any language of your choice as long
  167.     as your output matches this file format.
  168.     
  169.     By giving the appropriate source and destination locations of 
  170.     each point, other types of point-based animations can be created.
  171.     The supplied data file star.tra is an example: it animates a 
  172.     transformation of a horizontal-vertical star into a diagonal star.
  173.  
  174. HOW TO COMPILE
  175.     As distributed, the code is compilable with Turbo C and MASM using
  176.     the MAKETC.BAT file.  Turbo C 1.5, 2.0 and MASM 5.0 were tested, but 
  177.     other versions should work as well.
  178.  
  179.     The code was developed with Datalight C 2.20 and Arrowsoft ASM 1.00d.
  180.     To compile in this environment, comment out the 'TURBOC equ 1' line and
  181.     uncomment the 'DLC equ 1' line in the file EXPA.ASM before compiling.
  182.  
  183.     To use with other compilers, the segment and group names should be 
  184.     redefined according to the compiler's manual.  A generic command 
  185.         sequence to make the executable would be:
  186.  
  187.         masm /mx expa ;
  188.         cc explod.c expa.obj
  189.  
  190. BUGS/MISFEATURES
  191.     - With some machines running under DOS 3.2, if a lot of keys are 
  192.       pressed in a very short time (such as when you press your hand
  193.       on the keyboard), the DOS message "FATAL: stack failure" appears 
  194.       (if your BIOS can print text in graphics mode) and the machine 
  195.       will lock up.  To recover, press the reset button if there is one 
  196.       or turn the machine off and on.  To avoid this problem, either 
  197.       don't hit the keys so fast next time, change to a different version 
  198.       of DOS, or change your machine (here's the excuse that you've been 
  199.       looking for for getting that 386 box :-).
  200.     - Explosions "wrap around" on the four edges of the screen.  
  201.     - The program allocates all available memory from DOS when it starts
  202.       (if you don't like this then set a limit in MemInit() in explod.c).
  203.     - This program has not been tested much in CGA mode, so the supplied
  204.       demos and default parameters may not be very good on a CGA system.
  205.  
  206. AUTHOR
  207.     If you have any questions or comments, send them to:
  208.  
  209.     Dennis Lo          Internet: dlo@ubc-idacom.cs.ubc.ca
  210.     4516 Albert St.                    or
  211.     Burnaby, B.C.                ...!alberta!ubc-cs!idacom!dlo
  212.     Canada  V5C 2G5
  213.  
  214.     Send me your favourite set of command line parameters and/or data
  215.     files and I'll put it into the next release.
  216.  
  217.     Special thanks goes to:
  218.     - Erik Liljencrantz, for sending me his EGA/VGA modifications.
  219.     - Dave Lo, for the 'trails' suggestion and the use of his
  220.       VGA machine and his Turbo C.
  221.  
  222. LICENCE
  223.     This is free software, not shareware.
  224.  
  225.     You are free to use and distribute unmodified copies of this program.
  226.     Modified versions of the source and executable may only be distributed
  227.     if they are clearly distinguished from the originals with descriptive
  228.     messages.
  229.